C date and time functions
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
top
The C date and time functions are a group of functions in the standard library of the C programming language implementing date and time manipulation operations.cite-ref-1[1] They provide support for time acquisition, conversion between date formats, and formatted output to strings.
Contents
• History
• Example
• See also
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
History
The format string used in strftime traces back to at least PWB/UNIX 1.0, released in 1977. Its date system command includes various formatting options.cite-ref-2[2]cite-ref-3[3] In 1989, the ANSI C standard is released including strftime and other date and time functions.cite-ref-4[4]
Overview of functions
| | Identifier | Description |
|---|---|---|
| Time manipulation | difftime | computes the difference in seconds between two time_t values |
| Time manipulation | time | returns the current time of the system as a time_t value, number of seconds, (which is usually time since an epoch , typically the Unix epoch ). The value of the epoch is operating system dependent; 1900 and 1970 are often used. See RFC 868. |
| Time manipulation | clock | returns a processor tick count associated with the process |
| Time manipulation | timespec_get (C11) | returns a calendar time based on a time base |
| Format conversions | asctime | converts a struct tm object to a textual representation (deprecated) |
| Format conversions | ctime | converts a time_t value to a textual representation |
| Format conversions | strftime | converts a struct tm object to custom textual representation |
| Format conversions | strptime | converts a string with time information to a struct tm |
| Format conversions | wcsftime | converts a struct tm object to custom wide string textual representation |
| Format conversions | gmtime | converts a time_t value to calendar time expressed as Coordinated Universal Time [ 5 ] |
| Format conversions | localtime | converts a time_t value to calendar time expressed as local time |
| Format conversions | mktime | converts calendar time to a time_t value. |
| Constants | CLOCKS_PER_SEC | number of processor clock ticks per second |
| Constants | TIME_UTC | time base for UTC |
| Types | struct tm | broken-down calendar time type: year, month, day, hour, minute, second |
| Types | time_t | arithmetic time type (typically time since the Unix epoch ) |
| Types | clock_t | process running time type |
| Types | struct timespec | time with seconds and nanoseconds |
The timespec and related types were originally proposed by Markus Kuhn to provide a variety of time bases, but only TIME_UTC was accepted.cite-ref-6[6] The functionalities were, however, added to C++ in 2020 in std::chrono.
Example
The following C source code prints the current time to the standard output stream.
#include <time.h>
#include <stdlib.h>
#include <stdio.h>
int main(void)
{
time_t current_time;
char* c_time_string;
/* Obtain current time. */
current_time = time(NULL);
if (current_time == ((time_t)-1))
{
(void) fprintf(stderr, "Failure to obtain the current time.\n");
exit(EXIT_FAILURE);
}
/* Convert to local time format. */
c_time_string = ctime(¤t_time);
if (c_time_string == NULL)
{
(void) fprintf(stderr, "Failure to convert the current time.\n");
exit(EXIT_FAILURE);
}
/* Print to stdout. ctime() has already added a terminating newline character. */
(void) printf("Current time is %s", c_time_string);
exit(EXIT_SUCCESS);
}
The output is:
Current time is Thu Sep 15 21:18:23 2016
See also
References
cite-note-11. ↑ ISO/IEC 9899:1999 specification (PDF). p. 351, § 7.32.2.
cite-note-22. ↑ "PWB1 date system command - man page". www.tuhs.org.
cite-note-33. ↑ "date.c sourcecode of PWB1". www.tuhs.org.
cite-note-44. ↑ "Rationale for American National Standard for Information Systems - Programming Language - C - Date and Time". www.lysator.liu.se.
cite-note-51. open-std.org - Committee Draft -- May 6, 2005 page 355
cite-note-66. ↑ citerefmarkus-kuhnMarkus Kuhn. "Modernized API for ISO C". cl.cam.ac.uk.
External links